'\" t
.\"     Title: bugle-statistics
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: October 2007
.\"    Manual: Bugle user manual
.\"    Source: BUGLE 0.0.20150628
.\"  Language: English
.\"
.TH "BUGLE\-STATISTICS" "5" "October 2007" "BUGLE 0.0.20150628" "Bugle user manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
bugle-statistics \- specify formulae and metadata for bugle statistics
.SH "SYNOPSIS"
.sp
.nf
"\fIname\fR" = \fIexpression\fR
{
    precision \fI1\fR
    label "\fIlabel\fR"
    max \fI100\fR
}
.fi
.SH "DESCRIPTION"
.PP
By default,
\fBbugle\fR(3)
gets statistics from
~/\&.bugle/statistics, although an alternative location may be specified in the
\fBBUGLE_STATISTICS\fR
environment variable\&. Most users will just copy the sample file
doc/examples/statistics
from the source distribution\&. This manual page describes the format in more detail for those who want to set up custom statistics\&.
.PP
In order to understand bugle\*(Aqs statistics system, one must first understand how it uses
signals
and
statistics\&.
.PP
signals
.RS 4
A
signal
is a raw count of something, like number of frames, memory use, or load\&. For events, these are usually the total number of that event (like frame changes), rather than a rate\&. Signals are produced by generator filter\-sets like
\fBbugle-stats_basic\fR(7)
or
\fBbugle-stats_primitives\fR(7)\&.
.RE
.PP
statistics
.RS 4
Statistics are high\-level information computed from signals\&. For example, frame rate is computed from the number of frames signal and the time signal\&. Statistics also contain some metadata, such as the label to display with the statistic, and the number of significant digits to print\&. Logging filter\-sets (\fBbugle-logstats\fR(7)
and
\fBbugle-showstats\fR(7)) use this information to display the statistics\&.
.sp
The statistics file contains the formulae used to compute statistics from signals, as well as the metadata mentioned above\&.
.RE
.SH "SYNTAX"
.PP
Blank lines and lines beginning with a
#
are ignored\&. Statistics have the basic format shown in the synopsis\&. The expression consists of standard arithmetic operations (including parentheses), numbers, and signal expressions\&. When a signal expression is evaluated, it is done so over some interval of time (usually one frame, but
\fBkey_accumulate\fR
in
\fBbugle-showstats\fR(7)
allows for longer intervals)\&. Several types of signal expressions are available to determine how the signal is measured over that time:
.PP
\fBd("\fR\fB\fIsignal\fR\fR\fB")\fR
.RS 4
measures the change in the signal over the interval
.RE
.PP
\fBa("\fR\fB\fIsignal\fR\fR\fB")\fR
.RS 4
measures the average value of the signal during the interval
.RE
.PP
\fBs("\fR\fB\fIsignal\fR\fR\fB")\fR
.RS 4
measures the value at the start of the interval
.RE
.PP
\fBe("\fR\fB\fIsignal\fR\fR\fB")\fR
.RS 4
measures the value at the end of the interval
.RE
.PP
For measuring rates, use the ratio of two
\fBd\fR
expressions\&. For example, the default configuration defines the frame rate as
.sp
.if n \{\
.RS 4
.\}
.nf
"frames per second" = d("frames") / d("seconds")
{
    precision 1
    label "fps"
}
.fi
.if n \{\
.RE
.\}
.PP
For statistics not defined by rates (such as memory consumption), an
\fBa\fR
expression is generally sufficient\&.
.PP
Expressions are evaluated using floating\-point arithmetic, applying the usual rules of operator precedence\&. If an expression evaluates to a non\-finite value (infinity or
NaN) it will not be shown at all\&. A non\-obvious application this is that given two expressions
\fIE\fR
and
\fIF\fR, the compound expression
\fIE\fR / \fIE\fR * \fIF\fR
means
\(lq\fIF\fR unless \fIE\fR is zero\(rq\&.
.PP
The lines between the
{
and
}
contain metadata\&. The metadata keywords are:
.PP
\fBprecision\fR \fIdigits\fR
.RS 4
the number of digits to show after the decimal point
.RE
.PP
\fBlabel\fR "\fItext\fR"
.RS 4
the text to show with the statistic when logging
.RE
.PP
\fBmax\fR \fInumber\fR
.RS 4
a maximum value for the statistic, used to scale graphs to the correct height
.RE
.PP
\fBsubstitute\fR \fInumber\fR "\fIlabel\fR"
.RS 4
causes
\fIlabel\fR
to be used as the value if the numerical value was
\fInumber\fR
.RE
.SS "Wildcards"
.PP
A
*
may be used in the name of a signal\&. If the expression for a statistic contains any wildcards, it is a
wildcard statistic\&. When a wildcard statistic is selected for logging, it is instantiated zero or more times, with every possible replacement for the wildcard which yields a valid expression (in the sense that all the resulting signals must exist)\&. If
*
appears several times in the expression, all occurrences are replaced with the
\fIsame\fR
value in each instance\&.
.PP
In order to differentiate the instanced statistics, a
*
may also appear in the
\fBlabel\fR\&. This is again replaced with the same string used to replace the wildcards in the expressions\&.
.PP
For an example of a wildcard statistic in practise, see the
calls per frame
statistic in the sample statistics file\&.
.SH "FILES"
.PP
~/\&.bugle/statistics
.RS 4
Formulae and metadata for statistics
.RE
.SH "ENVIRONMENT"
.PP
\fBBUGLE_STATISTICS\fR
.RS 4
If set, defines the location of the statistics file, overriding the default above\&.
.RE
.SH "AUTHOR"
.PP
bugle
is written and maintained by
Bruce Merry\&.
.SH "SEE ALSO"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBbugle\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBbugle-logstats\fR(7)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBbugle-showstats\fR(7)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBbugle-stats_basic\fR(7)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBbugle-stats_calls\fR(7)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBbugle-stats_primitives\fR(7)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBbugle-stats_fragments\fR(7)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBbugle-stats_calls\fR(7)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBbugle-stats_nv\fR(7)
.RE
